execution, db/state: StateCache follow-ups - #22159

The if-absent check+insert was Get-then-Add on a per-call-locked LRU, so
a conditional writer could check (absent), lose the CPU to an
authoritative Put, then clobber it. Serialize same-key writers: striped
mutexes in GenericCache, a bind mutex around the CodeCache addr-to-code
binding. Red-tested by hammering a single key with a concurrent
Put/PutIfAbsent pair — pre-fix the stale value won within a few thousand
rounds.

…sent rationale

Route Put/PutIfAbsent and PutCodeWithHash/PutCodeWithHashIfAbsent through
shared private cores so the nil-cache and KeyCommitmentState guards live in
one place, matching the GenericCache/CodeCache shape. State the if-absent
rationale once on Cache.PutIfAbsent; the other sites keep terse pointers.

CodeCache.putCode drops zero-length puts, so the comment's 'no code' claim
was wrong (flagged by Copilot review; the wording predates this PR).

Extracts just the codeHash field from a SerialiseV3-encoded account record,
skipping the full decode (balance parse, codeHash interning) that
DeserialiseV3 pays. Bounds-checked against truncated records and faithful to
CodeHash.IsEmpty for non-canonical records that spell out the empty/zero
sentinel. Groundwork for #22120 finding 7: SharedDomains.codeHashForAddr runs
this per mem-hit on the codeHash fast path.

…p-in-flight assert

Three of the #22120 findings against the cache package itself:

Finding 11: GenericCache.Delete and the lazy stale-drop inside GetWithTxNum
removed entries outside the put stripes, so a removal interleaved between
put's data.Get and data.Add double-subtracted the displaced entry's size
(once via freelru's OnEvict, once via put's update delta) — currentSize
drifted one entry per occurrence and never healed. Both removal paths now
take the key's stripe, with a re-check under lock. Hammer tests reproduced
the drift (exactly one entry size) before the fix and run race-clean after.

Finding 12: new ContainsLive probes (Peek-based — no hit/miss counters, no
LRU recency) let conditional writers skip preparing a put that a live entry
would no-op: StateCache.put skips the value copy, and StateCache.HasLiveCode
lets the read-ahead prefetcher skip the keccak+copy for an already-bound
address. Advisory only — PutIfAbsent still decides under the key's stripe.

Enforcement (issue recommendation A, cheap variant): StateCache gains a
warmup-in-flight gauge (WarmupStarted/WarmupDone); Unwind panics under
ASSERT_STATE_CACHE when a cache-populating warmup is still in flight,
converting the drain-before-epoch-bump convention into a loud failure. The
drain-free getter remains tracked in #22116.

… domain progress

Read-ahead warmup follow-ups from #22120:

Finding 12: with if-absent semantics a live entry makes the conditional put
a no-op, but the prefetcher had already paid the keccak over the full
bytecode plus the value copy by then — the steady-state warm prefetch
allocated and discarded ~1-3 MB of hash+copy work per block. The code branch
now probes HasLiveCode before preparing the put; the accounts/storage copy
elision lives in StateCache.put (previous commit). A live binding makes the
prefetch a full no-op: it no longer populates content layers for its
superseded snapshot code either.

Latent-note fix: negative results (missing account, empty slot) carry no
step to derive an unwind bound from, and the synthetic step-0 stamp
((0+1)*stepSize-1) sat below every realistic unwind floor, making cached
negatives immortal. Correctness relied on the flush-callback overwrite
always firing. Negatives are now stamped with the domain's progress at
observation time (max committed txNum in the read snapshot), so they drop on
any unwind that could matter instead of outliving the fact they cache.

Also brackets the fire-and-forget warmBody goroutine with the new
WarmupStarted/WarmupDone gauge; the release is ordered before warmWg.Done so
a WaitForWarmup return implies the gauge is back to zero.

…old maxStep gates

The SharedDomains half of the #22120 findings:

Finding 9: the getLatestMetered read-fill was a second unconditional-Put
snapshot writer — an embedded-RPC eth_call straddling an FCU commit (or a
bounded read during an in-flight unwind) could overwrite the flush-applied
value with the pre-flush one, the same clobber shape #22146 fixes for the
warmup. Read-fills never carry newer information than a flush-apply, so both
fills (domain values and code) now use the if-absent puts.

Finding 4: the ASSERT_STATE_CACHE divergence check compared a cache hit
against a DB read bounded by the same maxStep the mem overlay published for
a key an in-flight unwind re-bound. In that window MDBX still holds the
not-yet-deleted dying row inside the bound, so the authoritative read
returns dead-fork bytes and the assert panicked on a legitimate below-floor
hit. The assert now runs only when no per-key bound is active. (The
Value==nil delete-only diff that produces this signal comes from legacy
V0-format persisted changesets; current V1 diffs are served from mem
directly — see DomainRoTx.unwind.)

Finding 7: the stateCache and branchCache maxStep gates were two copies of
the same rule differing only in a subtle divide/don't-divide unit
conversion; both now call one servableUnderBound helper carrying the shared
rationale, with the unit conversion explicit at each site. codeHashForAddr's
per-mem-hit full account decode is replaced by the targeted
DeserialiseV3CodeHash extractor.

Finding 5: ClearBranchCache and DetachBranchCache had no callers, and
DetachBranchCache's docstring advertised a fork-validation guard that was
never wired — correctness rests on the epoch-bumping sd.Unwind, which every
unwind path already funnels through. Deleted rather than wired: detaching
would cost fork validation its warm branch cache. ProbeReadLayers is kept —
it gains a caller in #22154.

Latent-note fix (SD side): negative read-fills are stamped with the domain's
progress instead of the synthetic step-0 bound, mirroring the warmup getter.

…rozenBlocks

Finding 10 of #22120: engine servers are live before ExecModule.Start, and
ValidateChain fires the read-ahead warmup before its too-far-away check, so
a payload validated in the pre-Start window warms the cache with pre-catchup
state — nil negatives included. Frozen-block processing advances state
without touching the cache (its SDs are never wired to it) and neither
clears nor epoch-bumps, so those entries stayed live through the whole
catch-up and were served cache-before-aggTx afterwards: stale value, wrong
root until restart. Start now drains any in-flight warmup and clears the
cache under the semaphore before frozen-block processing; no new warmup can
start until Start releases it.

No isolated unit test: reproducing needs a live engine server racing PFB
startup in the ms-scale pre-Start window. The change composes two
already-tested primitives (drainReadAhead, StateCache.Clear) at a point
where the semaphore excludes concurrent writers.

A WaitForWarmup landing between WarmupStarted and warmWg.Add saw a zero wg
counter and returned while the gauge was already raised, so a drain-then-bump
caller could trip the ASSERT_STATE_CACHE panic in StateCache.Unwind on a
correctly-drained warmup. Today's callers cannot interleave there (the module
semaphore excludes AddHeaderAndBody from every drain-then-bump path), but the
assert exists to be trustworthy when that convention is violated, so its
wiring must not manufacture false positives on its own. Raising the gauge
after Add restores the invariant from both sides: a Wait either returns
before Add (gauge still zero) or blocks until Done (gauge dropped first,
defers run LIFO).

Flagged by Copilot on #22159.

…e a resize

maybeGrow copied entries and then swapped generations, so a striped writer
that loaded the old generation before the swap landed its write in the
abandoned copy — the migrated (older) value resurfaced as live: a stale
serve, not the documented benign miss. Growth now publishes the new
generation first, fences the put stripes, and migrates each key under its
stripe with if-absent semantics; the grow trigger moves out of put's
striped section (the fence would self-deadlock). growLRU keeps the old
order: its content-addressed values are immutable per key, so a lost copy
there really is a benign miss.

Deleting the entry left the key absent, so a read-fill from a reader
straddling the deletion (a pre-delete snapshot) re-inserted the old value
as live — PutIfAbsent only defers to live entries — and the deleted
account or slot was served as canonical. A nil tombstone stamped with the
delete's txNum defends the key and drops on an unwind at or below the
deletion. The code layers keep the delete: they cannot represent
negatives.

…ine codeHash extraction, add negative-read benchmarks

Code negatives in the warmup getter no longer pay a DomainProgress call
and a liveness probe for a put CodeCache drops anyway. The
decodeAccountCodeHash wrapper was a pure pass-through — call
accounts.DeserialiseV3CodeHash directly. The new benchmarks bound the
negative-stamp cost: the keys-table LastKey is ~290 ns and the whole
cache-side fill ~0.5 us per cold negative (M2 Max), paid once per key
between invalidations.

… simplify put's grow trigger

The Cache.ContainsLive interface method had one caller — StateCache.put's
pre-check — whose only real value (skipping the keccak for already-bound
code) lives in HasLiveCode, which reaches CodeCache.ContainsLive
concretely; for domain values the probe traded a tens-of-bytes copy
against an extra Peek on the common miss path. putLocked now returns
whether the caller should grow, replacing the defer-ordering trick, and
warmBody builds its getter through one constructor.

TestGenericCache_PutIfAbsentDefersAcrossGrow is rebuilt to be
scheduling-proof: reaching Len >= startCap organically requires every
freelru shard full, which makes the hot key evictable and a stale insert
legitimate — a flake under CPU contention. The cache is now seeded below
capacity pressure with the hot key inserted last (the LRU victim is
always an older seed key) and the grow is forced by lowering curCap.

…deletion marker for the code cache

A code deletion was applied to the cache as a raw Delete, so a read-fill
from a reader straddling the deletion (a pre-delete snapshot) re-bound
the deleted code as a live hit — the same resurrection the account and
storage tombstones close, flagged by Copilot. An authoritative nil put
now binds a live no-code marker (versionedAddressID.deleted, stamped
with the delete's txNum): a valid negative on read, a binding
conditional fills defer to, replaced by an authoritative rebind and
dropped by an unwind at or below the deletion. The flush-apply writes
Put(CodeDomain, key, nil, txN), symmetric with the other domains.

Also tightens the DeserialiseV3CodeHash doc: it parses only up to and
including the codeHash field; later fields are not validated.

With the flush-apply writing tombstones and no-code markers, Delete lost
its last production caller — and any future call would reopen the
resurrection window the markers close, since removing an entry leaves
nothing for a straddling conditional fill to defer to. Drop it from the
Cache interface and every implementation so the wrong operation is not
expressible; the stale-drop keeps the stripe-serialized removal rationale.

The hammer tests that used Delete as a reset now race on fresh keys per
round, and the stale-drop drift check asserts the exact expected
residency instead of zero-after-delete.

…no-code deletion marker for the code cache"

This reverts commit 23bcf56.

…pply"

This reverts commit 561b29d.

Keep fresh-key setup in the PutIfAbsent concurrency tests and exact residency accounting in the stale-drop test. Restore only the Delete-specific coverage needed after extracting tombstones from this PR.

A capacity eviction is a size-subtracting writer the put stripes cannot
serialize: freelru picks its victim per shard (hash bits 16+), so an
insert on one stripe can evict a key whose own update — on another
stripe — sits between its Get and Add, and the update's
newSize-existing.size delta then double-subtracts the victim's size.
Replace the delta accounting (update and collision branches) with
remove-then-add, making the OnEvict callback the sole subtractor, as
putContent already does. Intentional removals (update, Delete,
dropStale) are compensated in the evictions metric, which also stops
stale drops counting in both staleEvicted and evictions.

Generation swaps stay unfenced here on purpose: the layers it backs are
content-addressed, so a lost write is a benign miss and a raced removal
resurrects correct bytes that drop on the next stale read. State that,
the counter approximation it implies, and that mutable-per-key values
belong on GenericCache's fenced swap instead.

… drain as a failed precondition

WaitForWarmup could return on context cancellation with the warmup
still running, so "WaitForWarmup returned ⟹ warmup gauge is zero"
held only for the completed-wait path; a payload validation racing
module shutdown could then bump the cache epoch un-drained (an open-tx
unwind never re-checks the context) and trip the ASSERT_STATE_CACHE
gauge assert. WaitForWarmup and drainReadAhead now report whether the
warmup fully drained — false only when the module context is cancelled
— and the epoch-bump/Clear call sites return instead of proceeding.
The DB-close caller keeps ignoring the result: it only needs a bounded
wait.

…he snapshot

AddHeaderAndBody read bra.stateCache separately for WarmupStarted, the
deferred WarmupDone, and warmBody's getter wiring, so a SetStateCache
racing the launch could split the pair (negative gauge) or tick one
cache's gauge while the workers populate another — the one whose gauge
Unwind asserts. Capture the pointer once and thread it through warmBody
so the Started/Done bracket and the puts all bind to the same cache.

…th threshold

…fenced copy

Grows are silent, so the once-per-lifetime writer stall of the fenced
copy (~150ms for the final 1GB-accounts step) surfaces as an
unexplained FCU/execution latency blip. One Debug line per grow with
the caps, copied count and the alloc/fenced split makes it
self-explaining.